Crate ledb_derive

Derive macro for defining storable documents

This crate helps to turn rust structures into documents which can be stored, indexed and queried.

Defining documents

You may turn any struct into a document using Document in derive annotation like this:

#[derive(Serialize, Deserialize, Document)]
struct MyDoc {
    // primary field
    #[document(primary)]
    id: Option<u32>,
    // other fields
}

This generates Document trait implementation for struct MyDoc. It requires single field marked as primary key per document. Currently primary key should be an integer only. Also it not needed to be an optional field, but in this case you should take care of parsing (for example add serde(default) annotation).

Defining key fields for indexing

To turn document field into key you can add document index annotation to it:

#[derive(Serialize, Deserialize, Document)]
struct MyDoc {
    // primary field
    #[serde(default)]
    #[document(primary)]
    id: u32,
    // unique string key
    #[document(unique)]
    title: String,
    // normal string index
    #[document(index)]
    keywords: Vec<String>,
    // unique int key
    #[document(unique)]
    timestamp: u64,
}

Overriding key types

In some cases it may be ambiguous to determine actual type of key by field type. For example, when you try to index binary data using Vec<u8>, the actually determined key type is an integer (u8). So you required to override key type manually using annotation like so:

#[derive(Serialize, Deserialize, Document)]
struct MyDoc {
    // ...
    #[document(unique binary)]
    #[serde(with = "bytes")]
    hash: Vec<u8>,
}

Nested documents

Of course you can add nested documents which may also have key fields:

#[derive(Serialize, Deserialize, Document)]
struct MyDoc {
    // primary field
    #[document(primary)]
    #[serde(default)]
    id: u32,
    // ...fields
    // simple nested document
    #[document(nested)]
    meta: NestedDoc,
    // list of nested documents
    #[document(nested)]
    links: Vec<Link>,
    // map of nested documents
    #[document(nested)]
    props: HashMap<String, Prop>,
}

The primary key field may be omitted for nested documents only. The nested documents should be marked as nested explicitly:

#[derive(Serialize, Deserialize, Document)]
#[document(nested)]
struct NestedDoc {
    // ...fields
}

NOTE: When serde(flatten) is used the key fields of nested documents will be transferred to owner.

Simple usage example

extern crate serde;
#[macro_use]
extern crate serde_derive;

extern crate ledb_types;
#[macro_use]
extern crate ledb_derive;

#[derive(Serialize, Deserialize, Document)]
struct MyDoc {
    // define optional primary key field
    #[document(primary)]
    id: Option<Primary>,
    // define unique key field
    #[document(unique)]
    title: String,
    // define index fields
    #[document(index)]
    tag: Vec<String>,
    #[document(unique)]
    timestamp: u32,
    // define nested document
    #[document(nested)]
    meta: MetaData,
}

#[derive(Serialize, Deserialize, Document)]
#[document(nested)]
struct MetaData {
    // define index field
    #[document(index)]
    keywords: Vec<String>,
    // define other fields
    description: String,
}

It will generate the Document traits like so:

impl Document for MyDoc {
    // declare primary key field name
    fn primary_field() -> Identifier {
        "id".into()
    }
    
    // declare other key fields for index
    fn key_fields() -> KeyFields {
        KeyFields::new()
            // add key fields of document
            .with_field(("title", String::key_type(), IndexKind::Unique))
            .with_field(("tag", String::key_type(), IndexKind::Index))
            .with_field(("timestamp", u32::key_type(), IndexKind::Unique))
            // add key fields from nested document
            .with_fields(MetaData::key_fields().with_parent("meta"))
    }
}

impl Document for MetaData {
    // declare key fields for index
    fn key_fields() -> KeyFields {
        KeyFields::new()
            // add key fields of document
            .with_field(("keywords", KeyType::String, IndexKind::Index))
    }
}

Derive Macros

Document